Turnbull China Bikeride/Turnbull China Bikeride - Disc 1.iso/ARGONET/PD/PROGRAMMING/TEMPLED_.ARC/!TemplEd/Manual

Text File | 1996-10-20 | 29KB | 717 lines

                            TemplEd User Manual
                            -------------------


0. Contents
___________

  1. About TemplEd
  2. About this manual
  3. Starting the program and loading files
  4. Opening and closing a template window
  5. Selecting icons
  6. Moving and resizing icons
  7. The "Icon Edit" dialogue window
  8. Moving and resizing windows
  9. The "Window Edit" dialogue window
  10. TemplEd's menus
  11. Shortcuts
  12. "Hidden" features
  13. Customizing
  14. Credits
  15. Copyright notice
  16. Addresses
  17. Finally


1. About TemplEd
________________

TemplEd is a template editor. With it, you can create and edit Template
files, which contain definitions of the windows used by an application. It
is therefore only useful for people who write programs that run in the
desktop.

If you want to know what can be in template definitions, and how they can
be read by a program, read the information about the SWIs
Wimp_CreateWindow, Wimp_CreateIcon and Wimp_LoadTemplate. This can be found
in the RiscOS PRM (Programmer's Reference Manual), and on-line in Guttorm
Vik's !StrongHlp application.

TemplEd is FreeWare. For conditions of use, read the copyright notice at the
end of this manual.


2. About this manual
____________________

If you are an experienced user, the !Help file will probably contain enough
information for you to get started. You may want to skip the boring
discussion of TemplEd's operation that follows. However, there are some
technical details that may be of interest. These have been marked with <TD>.
There is also a list of operation shortcuts and "hidden" features at the end
of this manual.


3. Starting the program and loading files
_________________________________________

After you have double-clicked on the application, the program installs
itself on the icon bar. A double-click on a Template file also starts
TemplEd, after which TemplEd loads the file.

You can load a template file by:

* Double-clicking on a Template file. If TemplEd is running and has not
loaded any templates, it loads the file. Otherwise, a new copy of TemplEd is
started.

* Dropping the file on the TemplEd icon on the icon bar. TemplEd deletes the
currently loaded templates, and loads the new file. If the current templates
have been modified, TemplEd first asks you to confirm before deleting them.

* Dropping the file in the Templates window. TemplEd adds the templates in
the file to the currently loaded ones.

If the file is called "Templates", then TemplEd will look for a sprite file
called "Sprites" in the same directory. If there is such a file, TemplEd
will assume that it contains the sprites to be used with the templates, and
automatically loads the sprite file as well.

Other sprite files with sprites used in the templates, can be loaded by
dropping them on the icon bar icon.

When you drop an application on the icon bar icon, TemplEd will load the
file "Templates" in the application directory (if present). If there is a
sprite file called "Sprites" in that directory, TemplEd will also load it.


4. Opening and closing a template window
________________________________________

A click with Select on the TemplEd icon on the icon bar opens the Templates
window. This lists the currently loaded templates. A small window icon
before the name indicates what type of window it is (scrollbars, title). A
yellow background of this icon means that it is currently open.

You can open a template by double-clicking on its name. If the template was
already open, it is closed. The "Open" and "Close" entries in the menu serve
the same purpose.


5. Selecting icons
__________________

Many operation on icons can be done on a single icon but also on a selection
of icons. There are several ways to select (and deselect) icons:

* Click with Select to select a single icon while deselecting the others. A
click on the background of the window clears the current selection.

* Click with Adjust to select an icon, without changing the rest of the
selection. If the icon was already selected, it is deselected.

* A drag with the mouse creates a drag-box in the window area. When you
release the mouse button, all icons within the box are selected.

* There are "Select all" and "Clear selection" items in the menu.

<TD> Like most other template editors, TemplEd creates a window for each
template, and creates icons exactly as they have been defined. This means
that the Wimp reacts to the mouse just as it would when a program was using
the template. That's why a menu icon is hard to select: you can click on
it, but if you move the pointer away from the icon, the icon is deselected
again. The Wimp also interferes if you want to select several radio buttons
from the same ESG. Even if you click with Adjust, the Wimp deselects the
other buttons (unless their 'Allow adjust' bit is set). You can select these
"difficult" icons with a drag-select.

<TD> If you want to check the behaviour of icons to mouse clicks, without
TemplEd reacting to the clicks, press a combination of keys (e.g. Shift +
Alt) while clicking. That way you can check if the ESGs of radio buttons
are set right, if option buttons are switched on and off, etc.


6. Moving and resizing icons
____________________________

To move an icon or a selection, click inside the window with Select while
holding down the Shift key. An outline appears around the icon(s) that moves
with the pointer until you release the mouse button. During the operation,
the pointer shape is changed to a hand.

To resize an icon or a selection, click on it with Shift+Adjust. A "rubber
box" drag is started, allowing you to move one side. The side that is moved
is the one that was nearest to the pointer when you clicked. It is also
indicated by the pointer shape. Though a resize operation will usually be
done on a single icon, it is possible to resize more than one icon at a
time; the icons are scaled according to the size of the drag-box.

An alternative way to move or resize icons is by clicking on them without
using the Shift key, and keeping the mouse button pressed for about half a
second.

During the drag, you can move the pointer with the cursor keys. The left,
right, up and down keys move the pointer 1 pixel (in the expected
direction). If you press a cursor key in combination with the Shift key, the
movement is 4 times as fast.

Pressing the cursor keys without starting a drag first moves the selected
icons.


7. The "Icon Edit" dialogue window
__________________________________

Except for size, position and number, all properties of an icon can be set
from the "Icon Edit" dialogue window. To open this window, click with
Shift+Menu, or choose the "Icon ⇨ Edit..." entry in the menu.

Icon flags can be set by clicking on the buttons, text and sprite names can
be entered in the appropriate fields. Use the up and down arrow keys to move
the cursor around. Some fields (e.g. button type, colours, font name) can
contain a limited number of values. These can be selected either by clicking
on the arrow icons to the left and right, or by clicking a mouse button
while the pointer is over the field. This pops up a menu from which you can
select a value.

<TD> The "1:1" button for the font is the only button not connected to an
icon flag. When on, it keeps X and Y size of the font equal, so you don't
have to set them both.

The changes to the icon only take effect if you press the "Update" icon.
"Exit" closes the window, leaving the icon as it was since the last update,
and "Update & Exit" combines the two.

<TD> If the indirected text that you entered is longer than the "Max
size" field allows, TemplEd automatically increases the maximum. It also
sets the "Indirected" flag if the text or sprite name uses more than 12
characters.

When you edit a selection of icons, not all fields can be modified (to be
exact: only the icon flags). The unchangeable fields are shaded. When you
press "Update" or "Update & Exit", the changeable fields are modified in
all selected icons.

In some cases, you may only want to change one field (e.g. set the button
type of all icons). To do this, click Menu above the "Update" or
"Update & Exit" button. A menu pops up from which you can select the flags
that must be changed.


8. Moving and resizing windows
______________________________

Usually, you can move a window by dragging the title bar, and you resize it
by dragging its resize icon. But some windows don't have a resize icon, and
some don't even have a title bar. You could of course edit the windows, give
them a title bar or resize icon, and remove these when you are done. But in
TemplEd, it is also possible (and much faster) to move and resize windows
directly. Use Ctrl+Select to move a window, and Ctrl+Adjust to resize it.

The work area of the window can also be resized with the mouse, with
Ctrl+Alt+Adjust. When you release the mouse button, the work area is set so,
that it stretches to the bottom-right corner of the visible part of the
window.

<TD> To enable the work area to expand, it is made very large at the start
of the drag. This is visible if your window has a scroll bar. At the end of
the drag, the area is shrunk again to the desired size.

Just as with moving and resizing icons, the cursor keys can be used during
the drag to position the mouse pointer.


9. The "Window Edit" dialogue window
____________________________________

Editing the data of a window is split in two parts. Flags, colours and
button type are edited in the "Window Edit" dialogue window. This window
is opened when you click Ctrl+Menu over the window, The contents of the
title bar are edited separately, using the "Icon Edit" window. It is
accessible with a Shift+Menu click while the pointer is over the title bar.
Both dialogue windows can also be opened from the menu.

<TD> The "transparent" colour number 255, that has a special meaning as the
title foreground colour or as the work background colour, is only selectable
from the colour menu, not by clicking on the arrow icons.


10. TemplEd's menus
___________________

Most entries in the menus ought to speak for themselves. Some others may
take a small explanation:

10.1 The "Window" menu

  Create icon...

  Opens the Palette window. In the Palette, you can select one or more icons,
  and copy these to one of your templates (by Shift-dragging them).

  You can change the contents of the Palette, see the section "Customizing"
  at the end of this manual.

  Icon/Selection ⇨ Renumber ⇨

  You can renumber single icons or selections. When a selection is
  renumbered, the icons are numbered from top to bottom and from left to
  right.

  <TD> It is not possible to give an icon a number that is equal to or
  higher than the number of icons in the template. If for instance there
  are 10 icons, they are always numbered from 0 to 9. You may enter a
  higher number but TemplEd will decrease it to 9. (In fact, what TemplEd
  does when renumbering is swap the definitions of two icons: the one that
  you want to renumber, and the one carrying the new number.)

  <TD> After renumbering an icon, TemplEd increases the new number by one
  and stores it. You can see this the next time you open the menu. This
  feature comes in handy when you renumber using Alt+Select (see
  "Shortcuts")

  Icon/Selection ⇨ Align ⇨

  Changes the selected icons so that they are lined up. There is a choice
  of aligning the left-hand sides, right-hand sides, top, bottom, and the
  centres (in either the horizontal or vertical direction).

  The icons can be either moved or resized. When resized, the coordinates
  of the icons stay the same except for the side that must be aligned.

  <TD> As an anchor for aligning, the outer icon is chosen. For horizontal
  aligning this is the leftmost icon, for top aligning the topmost, etc.
  This ensures that if the icons were inside the visible area before the
  aligning, they will remain fully visible afterwards (except for some cases
  when you align the centres).

  Icon/Selection ⇨ Space out ⇨

  Moves the selected icons so that there is a constant space between the
  icons. You can choose between horizontal and vertical distribution, and
  between setting a fixed space and using the available space between the
  outer icons. For example:

  Suppose you have four icons, positioned

     -----               -------  ---        ---
    |  A  |             |   B   || C |      | D |
     -----               -------  ---        ---

  Using a fixed space gives you something like

     -----    -------    ---    ---
    |  A  |  |   B   |  | C |  | D |
     -----    -------    ---    ---

  and choosing "Use available" results in

     -----        -------        ---         ---
    |  A  |      |   B   |      | C |       | D |
     -----        -------        ---         ---

  <TD> Before doing a Space out operation, TemplEd sorts the icons on their
  minimum coordinate. This means that the leftmost (or bottommost) icon
  always remains in place. It also means that if some icons have equal
  minimum X (or Y) coordinates, they may end up in any order.

  <TD> Both the "Align" and the "Space out" operations change the position
  of icons in only one direction. So if you do a horizontal Space out, the Y
  coordinates of the icons remain the same.

  Icon/Selection ⇨ Frame ⇨

  Puts a frame around the selected icons. The frame is used for grouping
  icons with related functions together. You have a choice of:
    * Taking the window itself as frame, or appointing one of the selected
      icons as 'frame' icon.
    * Using another icon as 'label', or none. The center of the label icon
      will be vertically aligned with the top of the frame icon.
    * Putting the label horizontally centered on the frame, or putting it at
      a fixed distance from the left of the frame.

  <TD> The icon with the lowest icon number is taken as the default frame
  icon; the next one in the selection is taken as the label icon.

  Icon/Selection ⇨ Min. size

  Minimizes the size of icons, keeping their bottomleft corner at the same
  position.

  <TD> It is very complicated to calculate the minimum size correctly,
  especially for icons with outline fonts, 3D borders or multi-line text.
  The procedure used may not always give the best results.

  Icon/Selection ⇨ Center

  Centers the icon (or icon selection) in the window, relative to the
  area that is currently visible.

  Icon/Selection ⇨ Same size

  Sets the size of the selected icons to be equal to the topleft one. The
  bottomleft corner is kept at the same position.

  Work area ⇨

  Leads to a window in which you can set the dimensions of the window work
  area. The "Minimize" button limits the work area to the maximum
  coordinates that are currently visible. The "Maximize" button sets the
  minimum size equal to the current window size. The "Default" button resets
  all values to those of a standard full-screen window.

  Misc ⇨ Sprite area

  Enables you to choose from which sprite area the sprites in the template
  are read. This can be either the Wimp area or a private area that is
  created when you drop a sprite file on the TemplEd icon.

  <TD> When saving templates, TemplEd always sets the sprite area to 1 (i.e.
  the Wimp area). If your program is using a private sprite area, it will
  have to re-direct the sprite area pointers after it has loaded the
  template.

  Misc ⇨ Ensure icons ⇨

  From this submenu, you can let TemplEd check the position of the icons,
  and move them if needed. The first item in the submenu make sure that all
  icons are within the work area, the second ensures that they are in the
  currently visible part of the window.

  Misc ⇨ Deleted icons ⇨

  Normally, when you delete an icon, it is only marked as deleted. Most of
  the icon data is retained, and the numbering of the other icons stays the
  same. If, later on, you create an icon, it may get the number of a
  deleted icon. Until that time, it is possible to "undelete" the icon.
  From this submenu, you can:
    * Undelete the deleted icons (e.g. if you accidentally deleted them)
    * Undelete them and move them outside the work area. This can be handy
      if you want to avoid that the icon numbers are used again when you
      edit other icons
    * Purge the deleted icons, so that there are no gaps in the numbering

  Note that for indirected icons, the indirected data can not be retrieved.

10.2 The "Templates" menu

  Export ⇨ Icon names

  This leads to a save-box from where you can save the icon names. The point of
  icon naming is that it allows your program to address icons by their name,
  instead of by the icon number (which may change when editing the template).
  That way, you don't have to adapt the source code after you modified the
  templates. The file with icon names can be read by the program when it starts
  up, or by a C compiler.

  You give an icon a name by putting an 'N'-command in the validation string.
  The format of the icon names in an exported file is
    <template name> + "_" + <icon name>

  You can save the names in 3 formats:
    * Basic    - creates a Basic file with a procedure PROCiconnames.
    * C        - creates a C header file in which the names are #define'd
    * MsgTrans - creates a text file which can be read by the MsgTrans module

  NB: This is an 'unofficial' feature, since icon names are not part of the
  template definition. The 'N'-command is not recognized by RiscOS, and has
  no effect on the appearance of the icon.

  Export ⇨ Templates

  This creates a textual description of the templates.

10.3 The icon bar menu

  Options...

    Opens a window in which you can set a number of options:
    * Double click starts edit
        When on, TemplEd reacts to double-clicks on icons, window title bar
        or background, by opening the appropriate Edit window.
    * Support 'Interface'/'AEH'/'WimpExt' module
        Provides limited support for one of these modules, by making the
        appropriate calls for redrawing icons. The modules provide a number
        of enhancements to the Wimp, among which icon borders with 3D look.
        Addresses of the people who made these modules are listed at the end
        of this file.
        <TD> Support is limited to redrawing icons, including selecting and
        deselecting them upon a click. Other features are not supported.
    * Allow duplicate template names
        If this option is off and a template is added with a name that
        already exists, the old template is deleted. Renaming a template to
        an existing name will also be refused.
    * Hatch user-redrawn templates
        When on, the background of windows of which the "Auto-redraw"
        flag is cleared, will be shown with a cross-hatch pattern.
    * Show icon info
        Enables or disables the Icon info window that shows information
        on the icon that the pointer is currently over.
    * Save icons as unselected
        When on, TemplEd stores all icons as unselected when you save any
        templates. Otherwise, the "selected" state of icons is saved with
        the rest of the data to the file, and when your program uses the
        templates, it will have to make sure that the correct icons are
        selected.
    * Delete icons moved outside
        If you move icons, and drop them outside a template window, they
        will be deleted if this option is on. When off, nothing happens to
        the icons. This option allows for fast deletion of icons.
    * Min. size: Ignore desktop font
        This option is only meaningful if you are working under RiscOS 3.50
        or later, where you can use an outline font for the desktop. If the
        option is off, and TemplEd is calculating the minimum icon size, it
        takes the text width in the Desktop font. However, that width may not
        be enough for other users, who use a different font. That ruins the
        layout. With this option on, TemplEd takes the text width for the
        system (BBC) font, which is usually wider than outline fonts.
    * Grid
        Locks the position of icons that are created or modified to
        a grid (as in !Draw). This makes it easier to get icons lined
        up properly. The grid size can be set by clicking on the arrow
        icons. There are two grids:
          - Icon size grid
            Locks all four corners of an icon, so that its size will be a
            multiple of the grid size
          - Icon position grid
            Locks only the bottomleft corner of the icon; this can be handy
            if you want to keep icons lined up, but want to keep their sizes
            unchanged
        Normally, the Icon position grid will be at least as large as the
        Icon size grid.
        <TD> If you are working in a high-resolution screen mode, it is
        advisable to use at least an Icon size grid of 2x4, so that your
        templates look the same in medium-resolution modes (like 12 and 15)
        <TD> TemplEd automatically adjusts the grid size in case of a mode
        change; the grid size must be at least equal to the number of OS
        units per pixel.

    The "Save & Exit" button stores the current settings to a file in
    the application directory, then closes the window. The "Exit" button
    just closes the window.

  Statistics...

    Opens the statistics window, showing the amount of memory that the
    templates will need if you use them in a program. The amounts can be
    shown in decimal or hexadecimal numbers.

    <TD> Note that the statistics window does not change as you modify your
    templates. The figures are re-calculated only when the window is opened
    or when you click on the "Decimal" or "Hex" buttons.

  Custom sprites ⇨ View/Edit

    "Run"s the file with the custom sprites that your templates are using.
    This normally means that !Paint will load the file.

  Custom sprites ⇨ Re-load

    Reads the sprite file again, e.g. after you have edited it with !Paint.

  Custom sprites ⇨ Reset

    Removes the sprites from memory; the templates will use the sprites from
    the Wimp area.


11. Shortcuts
_____________

* Opening the Icon Edit and Window Edit windows can be done from the menu,
but a faster way is to click on them while pressing a key. Shift+Menu opens
the Icon Edit window. Ctrl+Menu opens the Window Edit window. To edit the
title bar icon, click Shift+Menu on the title bar.

* The Edit windows can also be opened with a double-click with the Select
button. Double-clicks on an icon, on the background of a window, or on the
title bar open the appropriate Edit window. This only works if the
corresponding option is on.

* Inside the Icon Edit and Window Edit windows, pressing the F2, F3 and F4
keys has the same effect as clicking on the Update, Update&Exit and Exit
icons, respectively. The Escape key has the usual function which is exiting
without doing anything. Escape works not only in these two cases, but in all
windows with writable icons, such as the Save, Space Out and Options
windows.

* Many operations on icons can also be done with a control-key:

      Ctrl-A    Select all
      Ctrl-C    Copy selection
      Ctrl-D    Copy icons downward
      Ctrl-E    Edit selection
      Ctrl-F    Frame selection
      Ctrl-J    Open "Align" box
      Ctrl-K    Open "SpaceOut" box
      Ctrl-L    Copy icons to left
      Ctrl-Q    Close window (Ctrl-F2 works, too)
      Ctrl-R    Copy icons to right
      Ctrl-T    Edit title bar
      Ctrl-U    Copy icons upward
      Ctrl-W    Edit window
      Ctrl-X    Delete selection
      Ctrl-Z    Clear selection

(This only works if the window has the input focus, of course)

* Renumbering icons can also be done faster. Click Alt+Select on an icon,
and the icon gets the number that is visible when you open the "Icon ⇨
Renumber" menu. After the renumbering, this number is increased by one, so
you can number the icons sequentially by clicking on them one by one. A
click with Alt+Adjust does the same, except that the number is decreased
after the renumbering.

* A fast way to delete icons is by moving them outside the template. (This
only works if you have set the "Delete icons moved outside" option on.)


12. "Hidden" features
_____________________

TemplEd has a number of features that may not be immediately visible, but
can come in handy. (That's not counting the bugs ;-)

* It is possible to copy icons to other templates; just move the icons and
drop them into the other template. This makes it easy to use icons from
other templates.

* Extended icon info. When TemplEd starts, the Icon info window is small,
showing only the name of the template and number of the icon that the mouse
is over. If you click on the "toggle size" icon, it becomes full size and
also shows the dimensions of the icon plus the mouse position in window
coordinates. Still more icon info can be gotten from !Help, Acorn's
interactive help application. Open the help window, and move the pointer
over an icon.

* Fine-tuning when moving and resizing icons and windows is possible with
the cursor keys. The up, down, left and right keys move the pointer 1 pixel
(or 4 pixels, if Shift is pressed).

* Pressing Esc during dragging (icon move, resize, etc.) aborts the
operation.

* In the Icon Edit window, clicking Adjust on "Max Size" (the text itself,
not the writable icon) minimizes the value of the "Max Size" field.

* Closing the Templates window with the Adjust button opens a Filer window
of the parent directory of the file you are editing. Shift+Adjust also opens
the Filer window but does not close the Templates window. (This is, in fact,
standard Acorn practice for editor-like applications.)


13. Customizing
_______________

Apart from setting the options, you can also customize TemplEd's menu of
standard icons. Load the file "Templates" in the application directory into
TemplEd. The template "StdIcons" contains the definitions of the standard
icons. TemplEd loads them at program startup. You can change these
definitions to your liking.

For those who prefer windows without the 3D-look, there is an alternative
set of templates and sprites. To make TemplEd use them, rename them to the
default "Templates" and "Sprites", after you have given the standard "3D"
files a different name. (Note: you need Risc OS version 3.10 or later to
get the 3D effect.) Alternatively, run the "Use2D" Obey file in the "Extras"
directory; run "Use3D" to switch back to standard templates.


14. Credits
___________

Although the edit-dialogue windows are my own idea, not all features
implemented in TemplEd are. Some have been borrowed from RiscForm (the
version of !FormEd by The Risc Squad), some from Jonathan Marten's excellent
!DrawPlus (notably the Align and Space Out windows).

Martin Ebourne made the hires sprites file (!Sprites22). The MenuUtils
module which TemplEd uses was written by Alex Petrov.

TemplEd has also been much improved by the testing, comments and suggestions
of Stephen Burke, Martin Ebourne, Michael Ellis, Edwin Hautus, Paul Hobbs,
Rupert Johnson, Merlin Hughes, Olaf Krumnow, Paul Lebeau, Ian Palmer, John
Pullan, Niklas RÖjemo, John Tytgat, Julian Wright, and I'm sure I forgot
some others.


15. Copyright notice
____________________

This program is FreeWare. This means that I retain the copyright. You may
freely copy and distribute it, provided that it is complete with all
original files, and that you do not sell it. PD libraries may charge a
nominal fee for the cost of duplication, postage etc. When you use the
program, you do so entirely at your own risk. You may change the program to
suit your own needs. If it's a bug fix, or if you think it's an improvement,
then please send the changes to me at the address below.

The MenuUtils module is © Alex Petrov.


16. Addresses
-------------

Here are contact addresses for software used by or supported by TemplEd
Note that these are the most recent that I know, so they may be out of date.

The MenuUtils module (PD):
    Alex Petrov
    Bld. 1, Flat 107
    Kavkazsky
    boulevard, 29
    Moscow 115541
    RUSSIA.
    (e-mail: [e-mail])

The Interface module (PD):
    SoftWare Interrupt Developments.
    40 Castle Ings Gardens,
    New Farnley,
    LEEDS,
    LS12 5EG
    UK.

The AEH module (Shareware):
    Andrew Hersee
    The Red House
    Tallington
    Nr.STAMFORD
    Lincs.
    PE9 4RP
    UK.
    (e-mail: [e-mail])

The WimpExt module (PD):
    Jon Ribbens
    39 Nutkins Way
    Chesham
    Bucks.
    HP5 2BE
    UK.

StrongHelp (PD):
    Guttorm Vik
    Hølbekken 208
    N-5262 Arnatveit
    NORWAY
    (e-mail: [e-mail])


17. Finally
___________

If you have any questions, bug reports or suggestions for improvements,
you can contact me at the following address:

Lijnslagerstraat 204
NL-5625BP  Eindhoven
The Netherlands

or by e-mail: [e-mail]

Dick Alstein